ATOM Documentation

← Back to App

Creating and Training Agents

Complete guide to creating, configuring, and training your AI agents.

---

Overview

ATOM agents are AI assistants that learn from experience and can graduate through maturity levels. This guide covers:

  • Creating your first agent
  • Configuring agent capabilities
  • Training through feedback
  • Monitoring graduation readiness
  • Promoting to higher maturity levels

---

Part 1: Creating Your First Agent

Step 1: Navigate to Agents

  1. Log in to https://app.atomagentos.com
  2. Click **"Agents"** in the left sidebar
  3. Click the **"Create Agent"** button

Step 2: Configure Basic Settings

**Basic Information:**

FieldDescriptionExample
**Name**Agent name (required)"Finance Assistant"
**Description**What the agent does"Helps with financial analysis"
**Avatar**Visual representationSelect from presets or upload

Step 3: Select Agent Role

Choose what your agent specializes in:

**General Assistant**

  • All-purpose helper
  • Good for: General tasks, research, summarization
  • Capabilities: Web browsing, search, analysis

**Finance Agent**

  • Financial analysis and reporting
  • Good for: Reconciliation, forecasting, budgeting
  • Capabilities: Data analysis, report generation, calculations

**Marketing Agent**

  • Marketing campaigns and content
  • Good for: Social media, email campaigns, content creation
  • Capabilities: Writing, scheduling, analytics

**Developer Agent**

  • Code and technical tasks
  • Good for: Code review, debugging, documentation
  • Capabilities: Code analysis, testing, documentation

**Custom Role**

  • Define your own specialization
  • Specify custom capabilities

Step 4: Choose Initial Maturity Level

**Student** (Recommended for new agents)

  • ✅ Can: Read, search, browse web
  • ❌ Cannot: Make changes, send data
  • Use for: Learning, observation, research

**Intern** (After some training)

  • ✅ Can: Analyze, suggest, summarize
  • ❌ Cannot: Create new data, send emails
  • Use for: Analysis, recommendations

**Supervised** (Requires promotion)

  • ✅ Can: Create, send_email, moderate actions
  • ❌ Cannot: Delete, execute deployments
  • Use for: Most business tasks

**Autonomous** (Requires extensive training)

  • ✅ Can: All actions including high-risk
  • Use for: Fully automated workflows

Step 5: Create Agent

Click **"Create Agent"** to finish. Your agent is now ready!

---

Part 2: Configuring Agent Capabilities

Adding Skills

Skills determine what your agent can do:

  1. Navigate to your agent
  2. Click the **"Skills"** tab
  3. Browse available skills
  4. Click **"Add"** to assign skills

**Available Skills:**

**Data Skills**

  • web_browsing - Browse and research web
  • search - Search databases and APIs
  • analysis - Analyze data and trends
  • visualization - Create charts and graphs

**Communication Skills**

  • email - Send emails
  • slack - Post to Slack
  • reports - Generate reports
  • summaries - Summarize content

**Business Skills**

  • reconciliation - Reconcile data
  • forecasting - Predict trends
  • budgeting - Manage budgets
  • invoicing - Process invoices

Configuring Parameters

Fine-tune agent behavior:

**LLM Parameters**

{
  "temperature": 0.7,        // Creativity (0.0-1.0)
  "max_tokens": 2000,        // Response length
  "top_p": 0.9,              // Nucleus sampling
  "frequency_penalty": 0.0   // Reduce repetition
}

**Guidelines:**

  • **Temperature:**
  • 0.0-0.3 - Factual, precise (finance, data)
  • 0.4-0.7 - Balanced (general tasks)
  • 0.8-1.0 - Creative (writing, brainstorming)
  • **Max Tokens:**
  • 500-1000 - Short responses
  • 1500-2500 - Medium responses
  • 3000+ - Long, detailed responses

---

Part 3: Running Agent Tasks

Basic Task Execution

  1. Open your agent
  2. Type your task in the chat interface
  3. Click **"Execute"** (or press Enter)

**Example Tasks:**

**Student Level:**

"Search for recent articles about machine learning"
"Summarize this document"
"Find information about..."

**Intern Level:**

"Analyze this sales data and identify trends"
"Compare these two products"
"Suggest improvements for..."

**Supervised Level:**

"Draft an email to the customer about their order"
"Create a report from this data"
"Organize these files into folders"

Understanding Execution Results

After execution, you'll see:

**Result:**

  • Main output or response
  • Action taken (if applicable)
  • Sources or references

**Reasoning Trace:**

  • Step-by-step decision process
  • Alternatives considered
  • Confidence score

**Metadata:**

  • Execution time
  • Resources used
  • Episodes created

---

Part 4: Training Your Agent

Providing Feedback

Help your agent learn through feedback:

**Rating Responses**

👍 **Thumbs Up** - Positive feedback

  • Agent learns this approach works
  • Increases preference for similar patterns

👎 **Thumbs Down** - Negative feedback

  • Agent learns this approach doesn't work
  • Decreases preference for similar patterns

**Adding Notes**

  1. Click **"Add Feedback"**
  2. Provide detailed guidance:
  3. Select category:
  • accuracy - Correctness of information
  • helpfulness - Usefulness of response
  • safety - Safety and compliance
  • clarity - Clear communication

How Learning Works

**Experience Recording:**

Every execution creates an **episode** that captures:

  • Task description and context
  • Approach taken
  • Outcome (success/failure)
  • Confidence score
  • Your feedback

**Pattern Recognition:**

After 10+ episodes, the agent:

  • Identifies successful patterns
  • Detects failure modes
  • Generates adaptation suggestions

**Adaptation:**

The agent can:

  • Reinforce successful patterns
  • Avoid failed approaches
  • Calibrate confidence levels
  • Improve decision-making

---

Part 5: Monitoring Progress

Agent Statistics

Navigate to **"Statistics"** tab to see:

**Performance Metrics:**

  • Total executions: 150
  • Success rate: 94.6%
  • Average confidence: 0.87
  • Last execution: 2 hours ago

**Learning Metrics:**

  • Total experiences: 45
  • Successful patterns: 3
  • Adaptations available: 1

**Graduation Readiness:**

  • Current level: Student
  • Readiness score: 72%
  • Episodes until exam: 8
  • Eligible for: Intern

Graduation Readiness Formula

Readiness = (
  Zero-Intervention Ratio × 40% +
  Constitutional Compliance × 30% +
  Confidence Score × 20% +
  Success Rate × 10%
)

**Component Breakdown:**

**Zero-Intervention Ratio** (40%)

  • Agent operates without human help
  • Higher = more autonomous
  • Threshold: 40% for intern, 60% for supervised, 85% for autonomous

**Constitutional Compliance** (30%)

  • Adherence to safety guardrails
  • Higher = safer behavior
  • Threshold: 75% for intern, 85% for supervised, 95% for autonomous

**Confidence Score** (20%)

  • Well-calibrated confidence
  • Proper confidence matching actual success
  • Threshold: Varies by level

**Success Rate** (10%)

  • Overall task completion
  • Higher = more reliable
  • Target: >90% for all levels

---

Part 6: Graduation and Promotion

Understanding Graduation

Agents graduate through maturity levels based on performance:

**Student → Intern**

  • Requires: 70% overall readiness
  • 75% constitutional compliance
  • 40% zero-intervention

**Intern → Supervised**

  • Requires: 80% overall readiness
  • 85% constitutional compliance
  • 60% zero-intervention

**Supervised → Autonomous**

  • Requires: 95% overall readiness
  • 95% constitutional compliance
  • 85% zero-intervention

Triggering Graduation Exam

**Automatic:**

  • System checks eligibility every 30 episodes
  • Agent notified when ready

**Manual:**

  1. Navigate to agent
  2. Click **"Graduation"** tab
  3. If eligible, click **"Trigger Exam"**

The 5-Stage Graduation Exam

**Stage 1: Data Collection**

  • Reviews last 30 episodes
  • Extracts performance metrics
  • Validates sufficient data

**Stage 2: Constitutional Compliance**

  • Checks for safety violations
  • Validates compliance score
  • Must meet threshold

**Stage 3: Confidence Assessment**

  • Evaluates confidence calibration
  • Checks over/under-confidence
  • Must be well-calibrated

**Stage 4: Success Rate**

  • Calculates overall success rate
  • Analyzes failure patterns
  • Must meet threshold

**Stage 5: Final Determination**

  • Computes final readiness score
  • Validates all thresholds
  • Determines pass/fail

**Timeline:** Exam completes in < 1 second

Exam Results

**Passed:**

🎉 Congratulations! Your agent has graduated!

Previous Level: Student
New Level: Intern
Readiness Score: 0.72

New Capabilities Unlocked:
✓ Analyze data
✓ Suggest improvements
✓ Generate recommendations

**Failed:**

Exam failed. Continue training to improve readiness.

Failed Stages:
- Constitutional Compliance (72% < 75% threshold)

Recommendations:
- Focus on safety guardrails
- Review constitutional violations
- Improve compliance score

Post-Promotion Monitoring

After promotion, the system monitors performance for 7 days:

**Automatic Demotion:**

  • If success rate drops significantly
  • If constitutional violations occur
  • Can be disabled (manual review required)

**Manual Demotion:**

  • Admins can demote at any time
  • Records demotion reason
  • Agent retains learning

---

Part 7: Best Practices

For New Agents

  1. **Start at Student Level**
  • Learn agent's behavior
  • Build confidence in capabilities
  • Establish patterns
  1. **Use Clear Task Descriptions**
  • Be specific about requirements
  • Provide context when needed
  • Define output format
  1. **Provide Consistent Feedback**
  • Rate every execution
  • Add detailed notes
  • Be patient with learning

For Training Agents

  1. **Focus on Specific Domains**
  • Train agent on specific task types
  • Build expertise gradually
  • Don't overwhelm with variety
  1. **Monitor Patterns**
  • Review successful patterns
  • Address failure modes
  • Reinforce good behavior
  1. **Graduate at Right Time**
  • Don't rush graduation
  • Ensure readiness score is solid
  • Verify constitutional compliance

For Mature Agents

  1. **Continue Monitoring**
  • Watch performance post-promotion
  • Provide ongoing feedback
  • Adjust capabilities as needed
  1. **Expand Capabilities**
  • Add new skills gradually
  • Test in safe environments
  • Monitor impact on performance
  1. **Maintain Safety**
  • Review constitutional compliance
  • Audit high-risk actions
  • Adjust maturity level if needed

---

Part 8: Troubleshooting

Agent Not Learning

**Symptoms:**

  • Repeated mistakes
  • Low success rate
  • Poor pattern recognition

**Solutions:**

  1. Provide more explicit feedback
  2. Focus on specific task types
  3. Review and rate past executions
  4. Ensure sufficient episodes (30+)

Graduation Exam Fails

**Symptoms:**

  • Exam fails consistently
  • Low readiness score

**Solutions:**

  1. Check which stage failed
  2. Address specific weakness
  3. Continue training
  4. Trigger exam again later

Poor Performance After Promotion

**Symptoms:**

  • Success rate drops after graduation
  • New errors appear

**Solutions:**

  1. Review new capabilities
  2. Provide additional training
  3. Consider demotion if severe
  4. Adjust task complexity

---

Advanced Topics

Custom Agent Roles

Create specialized agents for your domain:

  1. Select **"Custom Role"** when creating
  2. Define custom capabilities
  3. Specify task types
  4. Configure parameters

Multi-Agent Coordination

Have multiple agents work together:

  1. Create specialized agents
  2. Define clear responsibilities
  3. Use cross-agent coordination
  4. Monitor joint performance

Integration with External Systems

Connect agents to your tools:

  1. Navigate to **"Integrations"**
  2. Connect required services
  3. Grant permissions to agents
  4. Test integrations safely

---

Next Steps

---

**Last Updated:** 2025-02-06

**Version:** 1.0.0